## Summary
### Why?

The speculation seams being introduced up-stack (path scorer, selector,
prioritizer) and durable links from other entities (a path→build
mapping) all need to refer to one specific path inside a batch's
speculation tree. Restating the full Base/Head split in every seam
output couples those contracts to path structure and forces consumers to
compare ordered slices; a single opaque identity lets each seam return
only what matters — a path ID plus its verdict — and gives durable links
a stable key to hang on.

### What?

`entity.SpeculationPathInfo` gains `ID`: assigned by the controller when
the path entry is first persisted, immutable thereafter, and unique
within its tree. Its format is the controller's choice and carries no
meaning — it is never parsed. Everything outside the tree names a path
by this ID. The tree store persists it transparently through the JSON
`paths` column, so the change is additive with no schema migration.

## Test Plan
✅ `bazel test //submitqueue/entity/...` — entity suite passes; the field
rides the existing JSON round-trip in the tree store.

## Issues


## Stack
1. @ #337
1. #315
1. #316
1. #317
1. #320
1. #331
1. #332
1. #333

## Summary
Add the first speculation seam and its limit counterpart from the
speculation RFC, as vendor-agnostic extension interfaces under
submitqueue/extension/speculation/.

enumerator: given a batch and its active dependencies ordered
oldest-first (queue arrival order — the ordering that fixes which
assumed-good Base prefixes exist), mechanically lists the candidate
Base/Head speculation paths — pure, deterministic, and purely
structural. It returns only []entity.SpeculationPath: identity, status,
and score are controller-owned, and the controller wraps each path into
the persisted tree entry (SpeculationPathInfo), keeping a clean
ownership boundary between the seam and tree state.

dependencylimit: the "how much" policy bounding how many active
(in-flight) dependencies a batch may speculate over. It is the
eligibility gate before enumeration; unlike the other speculation limits
it is controller-held rather than injected into a seam, keeping the
enumerator pure. The value is signal-driven, not a fixed constant.

Each follows the repo extension contract (conflict.Analyzer reference
shape): Factory.For(Config) (T, error) with Config carrying only
QueueName; behavioral knobs and limit signals are integrator-injected at
construction. Includes READMEs, gomock packages, and Makefile mock-gen
wiring. Interfaces only; concrete impls and controller wiring are
deferred.

## Test Plan


## Issues


## Stack
1. #337
1. @ #315
1. #316
1. #317
1. #320
1. #331
1. #332
1. #333

Add the scorer seam from the speculation RFC, as a vendor-agnostic
extension interface under submitqueue/extension/speculation/pathscorer/.

The scorer computes each speculation path's predicted-success score from
the current state: the per-batch scores of the path's base batches
(entity.Batch.Score) and which of those dependencies have resolved
(landed or build-passed), plus optionally other signals. It is a
prediction over live state, so the controller re-runs it on every
respeculate right after reconciling status, and persists the result; the
scorer owns only the formula.

The controller hands it the batch's speculation tree directly — the
subject it scores. Any richer signal an implementation needs (dependency
batch scores, historical pass rates) is injected at its Factory, not put
in the signature. It never writes: its only output is per-path scores
([]entity.PathScore — path ID plus fresh score, an entity-level
seam-output type alongside the path-decision type), which the controller
merges into the tree and persists, staying the single writer of tree
state; structure and status never pass through the scorer. Scores are
probabilities in [0, 1] — the contract every implementation must
satisfy, enforced by the controller on consume.

This is the per-path scorer, distinct from the existing per-batch score
stage (`extension/scorer`) that sets entity.Batch.Score — the path
scorer consumes those to score whole paths.

Follows the repo extension contract: Factory.For(Config) (Scorer, error)
with Config carrying only QueueName. Includes README, gomock package,
and a programmable fake. The speculation RFC's seam descriptions are
updated to match the identity-keyed minimal-output contracts (and gain a
design-decision entry for assigned path identity). Interface only;
concrete impls and controller wiring are deferred.


## Stack
1. #337
1. #315
1. @ #316
1. #317
1. #320
1. #331
1. #332
1. #333

Add the selector seam and its limit counterpart from the speculation
RFC, as vendor-agnostic extension interfaces under
submitqueue/extension/speculation/.

selector: the controller hands it the batch's speculation tree; it
returns per-path decisions (Promote/Cancel), each naming a path by its
ID (entity.SpeculationPathInfo.ID), for the paths it chooses to act on —
at most one decision per path, with conflicting duplicates treated by
the controller as a policy bug (applied first, logged and skipped
after). It is the policy seam — it reads the tree it is given and emits
decisions only, never writing status, and does not decide merging. The
controller maps each decision to a guarded status transition (Promote →
Selected, Cancel → Cancelling/Cancelled) and persists it, staying the
single writer of tree state. entity.PathDecision correspondingly names
paths by PathID rather than restating the Base/Head split.

selectionlimit: the "how much" policy bounding how many paths a batch
may build in parallel. It is the selector's companion — the selector
decides which paths, the limit decides how many. Injected into the
selector at construction and called by it, keeping the selector
interface limit-free; the value is dynamic, not a fixed constant.

Each follows the repo extension contract: Factory.For(Config) (T, error)
with Config carrying only QueueName. Includes READMEs, gomock packages,
and programmable fakes. Interfaces only; concrete impls and controller
wiring are deferred.


## Stack
1. #337
1. #315
1. #316
1. @ #317
1. #320
1. #331
1. #332
1. #333

…320)

Add the queue-wide prioritizer seam and its limit counterpart from the
speculation RFC, as vendor-agnostic extension interfaces under
submitqueue/extension/speculation/.

prioritizer: selection is per batch and blind to other batches, so it
cannot ration a shared build budget. The prioritizer sees every path
across the queue's in-flight batches that runs or wants to run (Selected
/ Prioritized / Building, each carrying its ID and score), ranks them —
scores are probabilities in [0, 1] per the path scorer's contract — and
returns sparse decisions naming paths by ID: Promote to admit under the
budget, Cancel to preempt, at most one decision per path. Whether it
preempts at all is implementation policy (sticky-slots vs preemptive).
It never writes: the controller maps each decision back to its tree and
applies the status transition under that tree's optimistic lock.
Prioritized thus means exactly "admitted under the queue's build budget,
cleared to build, not yet building".

prioritizationlimit: the "how much" policy bounding the queue's
concurrent speculation builds — the budget the prioritizer admits
against. Injected into the prioritizer at construction and applied by
it, keeping the interface limit-free; the value is signal-driven, not a
fixed constant.

Each follows the repo extension contract: Factory.For(Config) (T, error)
with Config carrying only QueueName. Includes READMEs, gomock packages,
and programmable fakes. Interfaces only; concrete impls and controller
wiring are deferred.


## Stack
1. #337
1. #315
1. #316
1. #317
1. @ #320
1. #331
1. #332
1. #333